<!DOCTYPE html>
<html lang="en">

<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Managing Bugs (Bugzilla and the Testsuite)</title>
<link rel="stylesheet" type="text/css" href="https://gcc.gnu.org/gcc.css" />
</head>

<body>
<h1>Managing Bugs (Bugzilla and the Testsuite)</h1>

<p>This section contains information mostly intended for GCC
contributors.</p>

<h2>Reporting and Fixing Bugs</h2>

<p>If you <em>find</em> a bug, but you are not fixing it (yet):</p>
<ol>
<li>Create a (minimal) testcase and <a href="./">file a bug report</a>.
</li>
<li>Enter the version number of GCC in the <em>Known To
Fail</em> field.  If you are reporting the bug against a release
branch, or the trunk, enter the version number of the next planned
release from that branch.</li>
</ol>

<p>If you want to <em>provide additional information</em> about an existing
bug report:</p> 

<ul>
<li>If the bug is a segmentation fault in the compiler,
<a href="segfault.html">provide information about its location</a>.
</li>
<li><a href="minimize.html">Minimize the test case</a>.</li>
<li>Try the test case with earlier and later versions of GCC to determine
which versions it affects and whether it is a
<a href="#regression">regression</a>.</li>
<li>If it is a regression, <a href="reghunt.html">identify the patch</a>
that introduced it.</li>
<li>Update the <em>Known To Fail</em> and <em>Known To Work</em> fields
to reflect passing and failing versions that you know about.</li>
</ul>

<p>If you <em>fix</em> a bug:</p>
<ol>
<li>Check in your fixes.</li>
<li>If there is already a testcase in the testsuite, remove the XFAIL.
Else, create a minimal testcase (maybe the bug tracker already provides one)
and add it to our testsuite, marking it as PASS.</li>
<li>If there is an associated bug report in the tracker, close it.</li>
<li>If, after your fix, the bug is present on some release branches
but not others, update the <em>Known To Fail</em> and <em>Known To
Work</em> fields to indicate which versions still have the bug.</li>
</ol>

<h2>Maintainer's View of Fields</h2>

<p>Bugzilla offers a number of different fields.  From a maintainer's
perspective, these are the relevant ones and what their values mean:</p>

<h3 id="status">Status</h3>

The status and resolution fields define and track the life cycle of a
bug.  In addition to their <a
href="https://gcc.gnu.org/bugzilla/page.cgi?id=fields.html">regular
descriptions</a>, we also use two adition status values:

<dl>

<dt><b>WAITING</b></dt>
<dd>The submitter was asked for further information, or asked to try
out a patch. The PR remains in that state until the submitter
responds.</dd>

<dt><b>SUSPENDED</b></dt>
<dd>Work on the problem has been postponed.  This happens if a timely
solution is not possible or is not cost-effective at the present time.
The PR continues to exist, though a solution is not being actively
sought. If the problem cannot be solved at all, it should be closed
rather than suspended.</dd>

</dl>

<h3 id="importance">Importance (Severity and Priority)</h3>

<p>The following two fields describe how serious a bug is from a user's
perspective (Severity) and what Priority we assign to it in fixing it:</p>

<table class="border padding5"><tr>
<td class="top">

<h3 class="center" id="severity">Severity</h3>
This field describes the impact of a bug.

<table>
<tr><th class="right">Critical</th>
<td>crashes, memory leaks and similar problems on code that is written
in a common enough style to affect a significant fraction of users</td>
</tr>
<tr><th class="right">Normal</th>
<td>major loss of functionality </td>
</tr>
<tr><th class="right">Minor</th>
<td>minor loss of functionality, misspelled word, or other
problem where an easy workaround exists </td>
</tr>
<tr><th class="right">Enhancement</th>
<td>Request for enhancement</td>
</tr>
</table> 

</td><td class="top">

<h3 class="center" id="priority">Priority</h3>
For <a href="#regression">regressions</a> this field describes the importance
and order in which a bug should be fixed.  Priorities are set by
the release management team only.  If you think a priority is wrong,
set it to P3 and add a note.
The available priorities are:

<table>
<tr>
  <th>P1</th>
  <td>Most important.  This generally labels a regression which the
    release manager feels should be addressed for the next release
    including wrong-code regressions.<br />
    A P1 regression blocks the release.
  </td>
</tr><tr>
  <th>P2</th>
  <td>This generally indicates a regression users will notice on a
    major platform, which is not severe enough to block a release though.
    This includes bugs that were already present in a previous release.
  </td>
</tr><tr>
  <th>P3</th>
  <td>The default priority for new PRs which have not been prioritized
    yet.  Priorities below P3 are not on the radar of release management.</td>
</tr><tr>
  <th>P4</th>
  <td>An important regression on a platform that is not in the list of
      primary or secondary targets or a regression that users
      will not see for release builds.
      This includes bugs with error-recovery or ice-checking keywords.
  </td>
</tr><tr>
  <th>P5</th>
  <td>A less important regression on a platform that is not in the list of
      primary or secondary targets.</td>
</tr>
</table>

</td></tr>
</table>

<p>As a general rule of thumb, within each priority level, bugs that result
in incorrect code (keyword <i>wrong-code</i>) are considered equally as important
to fix as those that lead to rejecting valid code (<i>rejects-valid</i>) and as
those that cause an ICE for valid code (<i>ice-on-valid-code</i>).  Lower in
importance, however, are <i>accepts-invalid</i> and <i>ice-on-invalid</i> bugs,
and less important still are <i>missed-optimization</i> opportunities.</p>

<p>Regressions that only affect more recent releases are prioritized over those
that also affect older releases.  For example, prior to the release of GCC 7,
a regression that was introduced in GCC 6 and that affects GCC 7 is considered
more important to fix in  GCC 7 than a regression that was introduced in GCC 5
(and is still present in GCC 6 and 7).</p>

<h3 id="assigned_to">Assignee</h3>

<p>This is the person in charge of resolving the bug.  Every time this
field changes, the status changes to NEW to make it easy to see
which new bugs have appeared on a person's list.</p>


<h3>Keywords</h3>

<p>These are used to further classify the problem reports. Follow the link
for a <a href="https://gcc.gnu.org/bugzilla/describekeywords.cgi">complete
list of the keywords including descriptions</a>.</p>


<h2>Procedures and Policies</h2>

<p><strong>Putting reports in components "C", "C++", and "optimization" in
state "NEW"</strong> requires that there is a reduced, small testcase.
This makes sure that all NEW reports are really analyzed and are ready to
be handed off to the people actually fixing bugs.</p>

<p id="regression"><strong>Regressions</strong> should be explicitly
marked as such.  The summary line should read</p>

<blockquote>
[<em>branches-to-fix</em> regression] <em>rest-of-summary</em>
</blockquote>

<p>where <em>branches-to-fix</em> is the list of maintained branches
(separated by slashes) that need fixing.
The target milestone should be set
to the next release of the newest active release branch that needs
fixing (the rationale is that a patch will have to go to the newest
release branch before any other release branch).
The priority of a regression should initially be set to P3.
The milestone and the priority can
be changed by the release manager and their delegates.</p>

<p><strong>If a patch fixing a PR has been submitted</strong>, a link
to the message with the patch should be added to the PR, as well as the
keyword "patch".</p>

<p><strong>Meta-bugs (reports with the keyword "meta-bug")</strong> are
used to group PRs that have a common denominator.  Meta-bugs do not have
testcases of their own, but provide links to regular PRs via Bugzilla's
"depends on/blocks" mechanism instead: they depend on the regular PRs.
Information concerning the majority of bugs blocking a meta-bug should
be added to the meta-bug instead of each single PR.</p>

<p><strong>Bugs with keyword "ice-on-invalid-code"</strong>, where GCC
emits a sensible error message before issuing an ICE (the ICE will be
replaced by the message "confused by earlier errors, bailing out" in
release versions) should get "minor" severity and the additional keyword
"error-recovery".</p>

<p><strong>Bugs in component "bootstrap"</strong> that refer to older
releases or snapshots/CVS versions should be put into state "WAITING",
asking the reporter whether they can still reproduce the problem and to
report their findings in any case (whether positive or negative).</p>

<ul>
<li>If the response is "works now", close the report,</li>
<li>if the response is "still broken", change the state to "NEW", and</li>
<li>if no response arrives, close the PR after three months.</li>
</ul>

<p><strong>Bugs that are in state "WAITING"</strong> because they lack
information that is necessary for reproducing the problem can be closed
if no response was received for three months.</p>

<p><strong>When closing a PR</strong> because it got fixed, please
set the <strong>target milestone</strong> to the first release where
it will be/has been fixed.  Also adjust the target milestone when a
fix is <strong>backported</strong>.  Finally, please adjust the
<em>Known To Fail</em> and <em>Known To Work</em> fields to record
what was fixed.</p>

<p><strong>Duplicate PRs</strong> should be marked as such.  If you
encounter a PR that is marked as "resolved fixed", but should be marked
as a duplicate, please change the resolution.  (You have to reopen the
PR before you can resolve it as a duplicate.)</p>

</body>
</html>
